home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
051-075
/
disk_069
/
asm68k
/
asm68k.doc
< prev
next >
Wrap
Text File
|
1992-05-06
|
54KB
|
1,144 lines
Asm68k 68000 Macro Assembler
Version 1.0.3
Docs
Date: 24-Apr-87
NOTICE:
THIS FILE AND THE PROGRAM IT DESCRIBES ARE COPYRIGHT © 1987,
W. WESLEY HOWE. ALL RIGHTS RESERVED. A LICENSE FOR USE AND
DISTRIBUTION WITHOUT PROFIT IS GRANTED TO POSSESSOR OF THIS FILE.
NO RIGHT OF ALTERATION OF THE PROGRAM OR DOCUMENTATION IS CONVEYED
WITH THIS LICENSE.
NO WARRANTY IS EXPRESSED OR IMPLIED HEREIN ON THE SUITABILITY
OF THIS PROGRAM FOR ANY PURPOSE AT ALL. YOU MUST RELY ON YOUR OWN
JUDGEMENT AS TO WHETHER THIS PROGRAM WILL OPERATE PROPERLY WITH
YOUR COMPUTER FOR WHATEVER PURPOSE YOU MAY DESIRE TO USE IT FOR.
ADDRESS ALL QUESTIONS, COMMENTS OR CRITICISM TO:
WESLEY HOWE
4800 LAKEMONT DR.
RALEIGH, NC 27609
(I may also be found at the Software Distillery's board (919) 471-6436,
MMS at (919) 779-6674 or (919) 772-9176 or (919) 779-5059, or ocassionally
on PLink (OPS833) and CIS (73277,260), although my appearances at the
last two are more erratic.)
=============================================================================
LIMITS:
Source-line length: 255 bytes (including newline)
Sub-expression length: 40 bytes
Parenthesis nesting: 16 levels
Symbol length: 31 bytes
Macro Size: 8,190 bytes
Number of Macros: Available RAM
Number of Symbols: Available RAM
Available RAM: 1,056,768 bytes maximum heap utilized
Macro Nesting: 8 levels
Include Nesting: 8 levels
Conditional Nesting: 16 levels
Macro Parameters: 10 per invocation
Sections: 255 maximum
Program size: 78,024 bytes (loaded)
Minimum free heap: 28,162 bytes
Total RAM necessary: 106,186 bytes
Constant size: 255 bytes
Storage size: 65,535 bytes
Strings: 255 bytes (or line length limit)
Minimum stack: 8,192 (recommended)
Operating System: AmigaDOS 1.2 (CLI Only)
==============================================================================
If you are an experienced 68000 Assembly language programmer, you will find
much of this material useful in understanding assembly language programming
on the AMIGA. If you are an experienced AMIGA assembly language programmer,
you may find much of the material boring, and will only want to use this as
a reference document. If you don't know assembly language, then this document
will not teach it, so you may need to get one of a number available reference
books on MC68000 assembly language programming.
In the following sections, Directives, Commands, Expressions and
Mnemonics are referred to. A Directive or Command is an instruction to
the assembler which causes a specific action to be performed. Some of these
add data to the object file, and some only affect the way assembly operations
are performed. A Mnemonic is the Pseudo-English abbreviation for an in-
struction the assembler is to translate into the appropriate numeric sequence
and include in the object file for the MC68000 processor to perform later,
when your program is run. An expression refers to any sequence of items
consisting of numbers, symbols with a numerical value, and the allowable math
operators which can be reduced to a single number value.
==============================================================================
Math & Logic Operators:
+ Addition - Subtraction or Negation
~ NOT << Left shift
>> Right shift & AND
| OR ! OR (for compatability)
^ XOR (Exclusive OR) / Integer Division
%% Integer Modulo * Integer Multiplication or
Current Program Counter Location
Like the Rotomola assembler, all expressions evaluate in strict Left-to-
Right order, as divided by parentheses. The Unary operators '-' and '~' need
to be offset from any adjacent operators with parentheses. Symbols and
constants may be mixed, and space or tab characters may be included. No
individual portion of the expression may exceed 40 characters (NOTE: a
'portion' would be any symbol or number alone.)
Some examples:
4+(7*2) Yields 56 4 + ( 7 * 2 ) Yields 56
4+7*2 Yields 22 -4*6 Yields -24
6*-4 Error 4(6*7) Error
('A'+1) Yields 66 "A" + 1 Yields 194
'ASDF'+0 Yields 1,095,976,006
Program Counter: The symbol * can be used as shorthand for the current
PC (relative offset) under the following criteria:
1> It is the FIRST (or only) character in an expression or
2> It is the second half of a binary operator (i.e. after
a valid math operator, with or without parentheses.)
Expressions that use the * or any symbol that refers to a relative
or external operation may only use plus and minus for math operations.
Any combinations within an expression that result in a value that will
not always generate reliable usage of relative locations will be flagged
with an expression error message.
===============================================================================
Numbers and Constants:
Binary: A binary number is either [1] prefixed with the '%'
(percent) character, or [2] followed immediately with
the letter 'B' (UPPER or lower case). It may contain
only the digits '1' or '0'.
Octal: An octal number is either [1] prefixed with the '@'
(at) character, or [2] followed immediately with either
the letter 'O' or the letter 'Q', in either case.
Only the digits '0' through '7' are valid.
Decimal: A decimal number contains only the digits '0' through
'9', and may be optionally followed immediately with
the letter 'D' (either case.)
Hexa-Decimal: HexaDecimal numbers contain the digits '0' through '9',
and the letters 'A' through 'F' (in either UPPER or
lower case.) They may be [1] prefixed with the '$'
(Dollar) character, or [2] they must start with a digit
and be followed immediately with either the letter 'H'
or the letter 'X', in either UPPER or lower case. A
leading '0' may be prefixed for the post-fix form.
Leading zeros do not affect the value of any of the number forms, although
the 40 character limit applies to them also.
Characters: Multiple ascii character may be included by enclosing
them in QUOTES. The single quote will yield an ascii
value, and the double quote will yield an ascii value
with bit 7 SET (or'd with 128). Multiple byte constants
are evaluated by successive left-shifts. Only the last
4 characters are retained as a 32-bit value.
Some Examples: The number 1,000 (one thousand) may be represented
any one of the following ways:
1111101000B 01111101000b %1111101000
1750Q 01750o @1750
1000D 0001000d 1000
3e8H 03E8h $3e8
'E0'-'AH'
==============================================================================
Assembly Line Format:
An input assembly line follows the following models:
Label1 Mnemonic Operand , MoreOperands ;comment
Label2: Mnemonic Operand
Mnemonic Operand
Label3: Mnemonic
LabelOnly
* a comment only
; another comment
Note that the LABEL either starts in the first column, or is followed by
a colon. The Mnemonic field is separated by at least one space or tab, and
never starts in the first column. Operands, where needed, follow, separated
from the Mnemonic by at least one space or tab. Multiple operands are
separated from each other by a comma (the comma flags the assembler that
there is another operand available.) An asterisk in the first position on the
line indicates a comment only line, or comments may follow complete operands
with a semicolon separator. Assembler directives occupy the Mnemonic position,
and comments are optional. Labels are allowed on all lines, and are required
for some assembler directives.
==============================================================================
Constants:
The following Assembler directives cause the inclusion of data in the
Object file:
DB Yields 8-bit values. Either STRINGS, Symbols, Labels, numbers
or expressions may be evaluated. Multiple operands need to be
separated by commas, and generate successive bytes up to
a limit of 255 bytes (the line-length limit should prevent
this from ever being reached.)
DW Yields 16-bit values, in Hi-Lo order. The format is the same
as the DB directive, except STRINGS will not be evaluated.
If the address is not a word address, a pad byte will be
appended to the previous line, and a non-fatal error message
will be issued.
DL Yields 32-Bit values. Otherwise equivalent to DW.
DC This directive is the same as DW. Appending .L or .B (in
either case) will change the function to be the same as
DL or DB, respectively. (DC.W is legal.)
ASCII This command yields a sequence of bytes equivalent to the
ascii value of the operands (delimited by quotes) provided.
Single quotes will yield the normal value, and double quotes
will yield values with bit 7 SET. Within the delimited
STRING, a '\' (backslash) character, followed by up to three
decimal digits will cause inclusion of a byte with the same
numerical value, or if followed by any other character will
allow the inclusion of that character immediately following.
(This is useful for including quotes and backslashes in the
string.) A limit of 255 values applies.
CSTRING This command is the same as ASCII, except an additional byte
with the value 0 is appended (as in the C language.)
PSTRING This is the same as ASCII also, except a leading byte with
a value equal to the number of bytes following is prepended
(as used in the PASCAL language).
ISTRING This variant of ASCII will cause the final character to have
it's most significant bit of the opposite (INVERTED) value
from the rest of the characters in the string (as defined by
the delimiting quotes). This form is popular among 8-bit
machines, and some BASIC interpreters. It's usefulness with
the new international 8-bit standard ASCII is questionable,
but it may be helpful, so it has been included anyway.
DCB This command accepts the .B .W and .L size specifiers (or
defaults to WORD.) It generates as many values as the operand
expression evaluates to (up to 255 bytes total), of the size
specified. WORD and LONG sizes are forced to an even address
alignment.
==============================================================================
Symbol and Labels:
A Label is an address designator. It is placed before a mnemonic or a
data location, and acquires a value equal to the relative program counter
value at that location. A standard Label may only be defined this way once
in a program, but may be referenced as many times as needed. It must start
with a letter, a period or the '_' (underscore) character, and may contain
only these characters, or the digits '0' through '9', without spaces up to
a total of 31 characters. When you define a label, it must appear as the
very first item on a line, or you must append a ':' (colon) character to it.
(You may have the colon in the first case also.) You must not use the colon
on the label other than when you define it, or you may get an erroneous
interpretation of your expression.
A Symbol starts off looking like a label, and follows the same rules, except
the following commands modify it to acquire a new type and value:
EQUATE Sets a permanent, absolute value equal to the value of the
expression following this directive. STRING values are not
allowed.
SETVAL Sets an absolute value which is retained until a new value is
set. You may not later use EQUATE on this label, but you can
EQUATE a different label to the set value.
EQUR Gives a value to the symbol which may later be used in place
of a standard data or address register. This is valid only
for D0-D7 or A0-A7 (SP is a synonym for A7). You cannot use
this value other than to reference a register in a MC68000
mnemonic.
REG Accepts a register-list operand for use with the MOVEM
mnemonic. A register-list looks like this:
A2-A7/D1/D3-D7
Which defines the registers A2 through A7, D1 and D3 through
D7. In fact, all the registers except A0, A1, D0 and D2. Only
the standard address and data registers may be defined in this
fashion.
MACRO Assigns a sequence of input lines, with replacable parameters,
which will later be substituted for any line which uses this
symbol as a mnemonic or command. More on Macros later.
These Directives must have a Label in the Label Field for assignment,
except for MACRO, which may have it's name in the operand slot.
You must avoid referencing a symbol before giving it a value, or the
assembler will complain (sometimes), because the forward reference will make
it type the symbol as a label, which is an address, not a number. Labels, of
course, may be referenced before use, and it's value will be substituted on
the second pass. In fact, this is the only reason you need a two-pass
assembler.
=============================================================================
Local (Numeric) Labels:
A line may be labeled with a special Local Label which attaches itself to
a specific offset from the last proper line label, as previously described.
A Local Label is a sequence of up to three decimal digits followed by the
'$' (Dollar) character. Like a regular Label, if it does not start at the
beginning of the line, it must be followed by a colon.
A Local Label may be referenced in an operand anywhere a line Label would,
but it's scope is only between one regular Label and the next. Each time a
new regular Label is used, the Local Label may then be redefined and reused
with a different value.
An example:
Start Jsr Initialize_Data
001$ Jsr Initialize_Serial
Move.b D1,ChangeFlag
Cmp.b #0ffh,D1
Bne 1$
Note that 001$ and 1$ will evaluate to the same location. You need not
start with one and may use any numbers you desire, as long as their value
does not exceed 999. Also, note that $1 and 1$ are interpreted differently;
the first is an absolute expression, and the second is a relative address.
Local Labels may not be used for Macro names, although they may be used
within Macros, and cannot be used to represent Numbers, EXTERNal or ENTRY
types.
==============================================================================
Conditional Assembly Directives:
The following Commands allow assembly to proceed until a matching ENDIF
Directive is found, or disable assembly until the ENDIF is reached if the
condition is not met:
IFEQ Expression EQuals zero. (e.g. 4-4)
IFGE Expression Greater than or Equal to zero. (e.g. 4-4 or 4-3)
IFGT Expression Greater Than zero. (e.g. 4-3)
IFLE Expression Less than or Equal to zero. (e.g. 4-4 or 4-5)
IFLT Expression Less Than zero. (e.g. 4-5)
IFNE Expression is Not Equal to zero. (e.g. 4-5 or 4-3)
The above conditionals are evaluated to 32 bits, but the condition decision
is based on their WORD (16-bit) value.
IFD Label following was already Defined (not just referenced.)
IFND Label following has Not yet been Defined.
IFC Both STRINGS following Compare (same length and characters.)
IFNC Both STRINGS do Not Compare (different length or characters.)
The last two conditional commands need two operands, separated by a comma.
They may be delimited with Quotes (single or double), or by a left bracket
'<' and right bracket '>' pair, or the first string will start at the first
character which is not a space or a tab, and end at the first occurrence of a
comma or space or tab, and the second will start at the next character which
is not a comma or a space or a tab and will end at the first space, tab, semi-
colon or newline character. To enclose spaces in the string, you must use
either the quote or bracket delimiters. To enclose quotes, use the brackets,
and to enclose brackets, use the quotes. Both quotes and brackets cannot be
passed together unless you use the spaces, but then you can't have spaces in
the string. Just shows to go you, everything is a compromise. Any backslash
character sequences are not expanded before comparison (except inside Macros.)
Each Conditional command DO level ends with an ENDIF command. DO levels
nest only to 16 levels, or a fatal error will be generated (whether the
assembly is on or off, each IFxx increases the level count, and each ENDIF
decreases the count; exceeding 16 or going below zero are fatal errors.) DO
levels are not active during a macro definition, but will be evaluated during
a macro expansion.
==============================================================================
Other Assembler Directives:
RESERVE Creates an uninitialized data storage area, with a size equal
to the expression following it. The size designators .B .W and
.L (any case) may be used, or WORD is assumed. The expression
following the Directive is expanded to the size specifier.
This is the only Directive which is not limited in size to 255
bytes for the result, but may yield up to 65,535 bytes.
ENDSRC Shuts off assembly for the current DO level. (See the section
on conditional assembly for DO level explanation.) If you
are not in a DO level, the source is read to the end of
file, but no assembly action will occur.
OPTION This command accepts the following operands only:
M - Allows macro call lines to print in the
assembly listing. (If List is on.) This
is the default condition.
NM - Hides macro call lines, showing expansion
lines only.
L - Turns on listing. (The default condition).
NL - Shuts off Listing.
(Neither of these commands override the command-line
switches directly, they only control the flow of data.
An assembly will still create a list file if not prohibited,
Option NL will just make it an empty file. If the list
file was disabled on the command line, Option L will
not send the listing anywhere. None of the operands are
case-sensitive.)
TITLE Accepts a STRING (delimited by quotes) which will label all
pages, if paging is not disabled. The Maximum title length
is 40 characters. Also cause pages to be numbered.
ORIGIN Sets the program counter to the value of the expression
following the command. Origin remains relative on AMIGA
output format.
PAGEUP Causes a page to end if paging is not disabled. A form-feed
character is sent, and a page heading with the optional
title (see TITLE) is printed.
SECTION this command causes a new section, or Hunk, to be created in
the AMIGA output format. The first operand must be a name
containing no spaces and having less than 40 total characters.
The second operand, if given, should be separated by a comma
and should be either CODE, TEXT, DATA or BSS. If none is given,
CODE is assumed. (only the first character is checked, however,
so DUMMY will yield a DATA section definition.) TEXT is
equivalent to CODE. Case is not significant on the section
type, but case is important for the name. If the section name
has been used before, assembly will proceed at the next
location as was previously defined, and the resultant code,
data or storage space will be coalesced into one Hunk. AmigaDOS
loads different hunks into different memory locations, so all
references to data between sections should be to Labels
declared as ENTRY (XDEF) to ensure assembly as absolute
locations. A warning is issued (unless shut off, see the
switches section) when this condition is detected. See the
AmigaDOS manual for more information on Hunks.
IDENTIFY This command should be followed with a name, which will
be given to the program unit (a program unit is a hunk or a
collection of hunks to be fed to the linker.) Only the first
name given will be used, subsequent uses are ignored. If the
IDENTIFY command is not used during an assembly, the object
file will be given a name that has 0 characters in it. (Null
string.)
EXTERN Followed by one or more Labels or symbols (separated by commas.)
These labels must not be defined within the entire assembly
source, and cause the assembler to generate the appropriate
external reference instructions in the object file (AMIGA
format only) for resolution by the linker. Multiple EXTERN
usage on the same Symbol name is ignored.
ENTRY Followed by one or more Labels or Symbols. These labels, which
need to be defined somewhere, allow locations within the
program unit to be visible to the linker to resolve other
program unit EXTERNal references. A program that consists of
more than one object file will need to have an ENTRY in one
unit for every EXTERN in the other units, or the program will
'BOMB' and probably either lock-up the machine or cause the
dreaded GURU to appear. References between different sections
must be to ENTRY labels, since the AMIGA loader will place
each section wherever it will fit, and resolve all these
different addresses. If you never use the section command,
the entire program will have to fit in the same place, and
might not be able to be loaded if there is not a spot big
enough for the whole thing (depending on how many tasks might
also be running, etc.) As for EXTERN, duplicate references
to the same name cause the second reference to be ignored.
EXECUTE This command will pass the quote delimited string following
it to AmigaDOS during the second pass. The current window
is the input and output. A more detailed description of the
Execute routine is located in the AmigaDOS manual, but
basically the same things you can do from the CLI may be
contained within the string and executed from within the
assembler. The Source, Object and any open Include files
will be locked, and cannot be accessed at this time. No
use is made of the return value from the program called.
CNOP This Directive causes null filler bytes to be inserted
into the object file until the desired alignment is
reached. There may be one or two values after the Directive,
separated a comma. The second value given, or the single value
is the desired alignment value you want, and the first value
when two values are given is how many more bytes to add beyond
this point. There may not be more than 255 bytes generated in
total to acheive the desired alignment, and no restrictions are
imposed on what alignment values can be used, but values that
are not powers of two will normally not generate a correct
alignment. If you want to set the Program Counter 2 bytes
beyond the next PC location evenly divisible by 8 use the
command like this:
CNOP 2,8
The predominant reason for using this command would be to
align data at specific offsets, and to create data structures
in specific formats.
===============================================================================
Include Files:
Up to 8 levels of include files may be inserted into the assembly with the
INCLUDE Directive. The syntax demands a Filename or Path, delimited by quotes.
Include file directory searches are supported by command-line parameters (De-
tailed in another section.) Include files may be called by Macros, and Macros
may be used by Include files, up to their respective nesting levels (8 each.)
The INCLUDE directive will cause the next source line to be read from the
named file as if the entire contents appeared in the original source file,
except line numbering will start at one again, and the line number will be
followed by a '+' (plus) sign. When the end of the Include file is reached,
the line number will revert to the one following the line which invoked the
INCLUDE Command.
Special provisions have been made to allow automatic and command-line
inclusion of header and/or macro definition files before assembly starts,
and these files do not count in the nesting level limits for Include files.
A later section will describe command-line parameters and the configuration
file.
A SPECIAL NOTE: Several of the existing include files from Commodore do not
Assemble correctly (particularly those in the exec directory.)
Many of the source lines in these files contain comments
which are delimited only by spaces and an asterisk. Asm68k
is not restrictive about spaces within an expression, and
tries to assemble the asterisk as a multiplication operator
with the words in the comment being looked at as labels, and
gives appropriate error messages. Make sure the comments are
stripped or delimited by a semi-colon. A few of the files
contain Macro error checks using an IFC \1,'' which will not
assemble correctly with Asm68k. Use IFEQ NARG instead. the
FUNCDEF file contains an expression 4*-6, which will not be
interpreted correctly as written. Change this one to 4*(-6).
Lists.i contains a parenthesized expression as an offset
for an address register. Asm68k will not accept parentheses
within 68000 mnemonics except when they are immediate type,
as the parentheses denote a register designation. These changes
will make both assemblers happy, and the include files more
portable between applications.
===============================================================================
Macros:
The best feature of the assembler, and the hardest one to master, is the
use of the MACRO command. A Macro is simply a sequence of source lines which
may be saved and inserted as often as wanted just by using the name you gave
it as a command. A Macro may contain any of the other Directives and Mnemonics
the assembler recognizes except another MACRO definition command, although
you may use the name of a defined Macro in your Macro (up to 8 levels deep.)
A Macro is defined (and it must be before being used) by placing the
MACRO in the Mnemonic Field, either before or after it's name. The name for
the Macro must follow the rules for Labels if it is on the left side, or if
it is on the right side it needs to be separated by at least one space or
tab from the MACRO Directive, and follow all the Label rules except it does
not need to be followed by a colon. All the subsequent lines up to the one
which contains the ENDMAC command will be saved for subsequent use.
The real power of Macros comes from their use with replacable parameters.
When you issue a Macro name as a Command, up to ten parameters (numbered
from one to nine, with zero for ten) may be included in a comma, space or
bracket separated list after the name for use within the Macro text. To make
these parameters appear in the Macro expansion, place a '\' (backslash)
character followed immediately (no spaces) with the digit of the parameter you
want in the definition. When the macro is expanded, the text will include the
parameter placed on the calling line, and will be evaluated just as if the
source had included it as it appears. Parameters are gathered and passed as
they appear, quotes and all.
The backslash character may be passed to the Macro by including two
backslashes in the calling line, and any non-numeric character following
a backslash other than a backslash will pass both the backslash and the
character following it to the Macro. To pass numeric sequences for use
in a string (such as with the ASCII directive), use two backslashes [as
in \\13, to put the sequence \13 , which puts a carriage return with the
quoted string].
Conditional Directives are effective within the Macro, under the same rules
as they follow elsewhere. If assembly is enabled, and the Directive MEXIT is
encountered, expansion of the Macro is suspended, and the next source line
will be the one following the Macro invocation line, after the assembler has
examined the remaining Macro text and resolved all the IFxx and ENDIF levels.
To make Macros respond differently with different numbers of passed para-
meters, the special symbol NARG (not case-sensitive) has been reserved. It will
yield a value equal to the number of parameters found on the invocation line
within a Macro expansion, and zero elsewhere.
One additional feature within Macros is the \@ (backslash followed by the
at character). While the Macro is being expanded, this combination is changed
to a period followed by three decimal digits. These digits increment starting
from zero every time a macro call is made that uses the \@ combination, and
will be used for the duration of that macro (a contained macro call will use a
new number, then when it ends the former macro's number will be used until it
ends. This allows unique symbol names to be generated within the Macro text,
allowing branch instructions to occur. Local (numeric) Labels are effective
within the Macro, but they do not attach to the Macro name, nor are they
canceled by the Macro invocation (unless the invocation line was labeled.) Note
that this sequence is significantly different from the usage in version 1.0.1.
==============================================================================
Do Nothing Directives:
The following directives are accepted by the assembler, but cause no action
and generate no code, just as if they were comments. They have been included
to allow use of source code written for other assemblers.
MASK2 FORMAT SPC
NOL OFFSET
Synonym Directives:
The directives in the left column are substitute names for the directives
in the right column, and were included for source compatability:
DS RESERVE
END ENDSRC
EQU EQUATE
SET SETVAL
TTL TITLE
ENDC ENDIF
ENDM ENDMAC
RORG ORIGIN
XDEF EXTERN
XREF ENTRY
RORIGIN ORIGIN
===============================================================================
Unimplemented Directives:
The following Directives, found in some other assemblers, have not been
implemented in this version:
IDNT FAIL LIST
LLEN PAGE PLEN
NOOBJ NOLIST NOPAGE
A startup Macro file has been included with this package to allow some
compatability if these are needed.
===============================================================================
Startup Configuration:
If a file named Asm68k.cnf (or with a filename the same as the assembler
with the extension .cnf) is found in the same directory spec the assembler was
called from, it is read and acted on. The current version only looks for two
items in this file, the pagelength (which must be greater than 11) and the
name (and path) of the startup file. The format is:
Page Length: 1 byte (11-255), binary
File Path: up to 31 bytes, ascii
Terminator: 1 byte, binary, value 0
Any remaining characters after the null byte are ignored. The assembler
next looks for the filename or path given, and if this file is found, it
is read and assembled as if it was the beginning of the Source file. All
lines from this file are numbered 0, and no warning or error occurs if the
file is not found (unless, of course, you were depending on these definitions
in your program, then you could have lots of error messages.)
Beware when building this file that the null character must be at the end of
the pathname or you may crash the system. You can create a file from the
keyboard using the command:
COPY con: to Asm68k.cnf
then typing a character for the pagelength (B is 66, the standard), following
it with the pathname for the startup file, followed with a control@ (CTRL key
and 2 key together), then ending it with a control\ (CTRL and \ keys together.)
If you make a mistake, you cannot edit the file, so do the control\ and start
over.
===============================================================================
Invoking the Assembler:
The assembler is designed to be run only from the CLI interface. If you
don't know how to find the CLI interface, read the manuals that came with
the machine before trying to use this program.
The minimum invocation must be the program name (Asm68k) followed with a
source filename (separated by at least one space from the program name.)
This will yield an assembly, with an object file output in the AMIGA format,
and a listing file. The filenames for these files will be created by
stripping any extension (period followed by characters) from the source
filename and appending .o for the object filename and .lst for the listing
filename. Any error messages will list to the screen.
Example:
Asm68k MyProgram.a
Outputs:
MyProgram.o (The relocatable binary object file)
MyProgram.lst (A combined source and hex object file)
If this isn't what you want, a wide variety of "switches" are supported
to control the usage of the assembler, and the descriptions follow:
(A switch is a parameter you type after the program name and source
filename, with an intervening space. These switches all start with the
minus sign '-' and may be followed immediately by a letter or letters as
shown below.)
-O Causes the OBJECT file to be generated (this is a default
value.) It may be followed immediately with a filename
containing no spaces, or type a space and then enclose the
filename in double quotes if it contains spaces. You may also
use the intervening space without quotes on a filename without
spaces if you like. A given object filename will be used
instead of the default filename normally used.
-L Causes the LISTING file to be generated (also a default.) The
usage is just like the -O switch.
-E Causes ERROR messages to list to the named file. Use like
above. On this switch, if no filename is given, a default
filename will be formed like the object and listing names,
using the extension .err
-V VERIFICATION file. Another name for the -E switch.
-H HEADER file. Causes a search for the filename given after the
switch (as above) which will be read as a source file before
the source file is read (but after the initialization file, if
enabled.) Just like the initialization file, if the file is not
found, no warning or error is issued directly. All the source
from this file will also be numbered as line 0.
-I An INCLUDE directory search path list should follow this switch
and should contain directory names (no spaces allowed) separated
from each other with plus signs '+', commas or spaces. If
spaces are used, then you must space the list off from the
switch and enclose the entire list in double quotes. Use of
this switch will cause the assembler to search for an INCLUDE
file in each of the named directories if it is not found in
the current one.
-X This switch should be followed immediately with up to 6
characters, and will cause the default object filename to be
formed by stripping the extension and appending a period and
the characters following the X.
-C This switch has been included for compatability. It should
be followed with only the following characters, as many as
wanted, with no spaces:
S Generates a symbol table at the end of the
list file (this is a default value.)
D Does nothing.
C Causes Case of all Labels and symbols to
be ignored. With this switch activated,
LABEL, Label and label will all be interpreted
as the same name. This is not the default.
X Does nothing.
-N This switch turns things off (NO.) Like -C, you should follow
it with a series of letters from the following list, without
any spaces:
S Turns off the SYMBOL table normally produced
at the end of the listing file.
L Stops the LISTING file from being generated.
E Inhibits the ERROR file, if you turned it on.
V A synonym for the E switch above.
P Inhibits the PAGINATION of the listing file.
O Inhibits the OBJECT file generation.
Q Inhibits the conversion of mnemonics to QUICK
form. The default is to convert allowable
values of ADD and SUB to the quick form if it
is safe (values already defined.)
X Keeps the assembler from stripping the eXten-
sion from the source filename when forming
default filenames.
R Causes the assembler to generate the object
code in a non-RELATIVE format. The format
used is the Intel format, and the program
counter is only output to 16-bits of
significance. No symbol or relocation infor-
mation is output, and no linker or loader
is available to operate on this format.
-R This is the relax switch. The following parameters should
follow the switch immediately, with no spaces:
M Stops the assembler from reporting that less
parameters were supplied for a macro than
were called.
R Eliminates messages about relative references
to other sections. Note that any mnemonic
that has a PC-relative mode available will
still assemble as PC-relative, and will not
run on the Amiga. Declare all references
between sections as ENTRY (XDEF). The linker
can be used so as not to include resolved
references in the load file.
> The right bracket, followed immediately with a filename, will
cause the signon, progress and all error messages to be
diverted by AmigaDOS to the named file when it is the first
parameter after the program name. If it is not the first,
the assembler will send the error messages to the named file.
All the above switches may be used in either UPPER or lower case, and will
generate the same results. The source filename should be the first parameter
after the program name, but only to avoid confusion. It must be the only
parameter not associated with a switch, and may not be given twice. The source
filename is the only mandantory command-line parameter.
==============================================================================
Other notes on use:
Case is normally significant on Symbols, Labels and Macro names unless the
-CC switch is used. The Directives, Mnemonics and special symbols will be
recognized in any mixture of UPPER and lower case.
The only truly reserved symbols are the following:
NARG MACRO ENDMAC ENDM A0
A1 A2 A3 A4 A5
A6 A7 D0 D1 D2
D3 D4 D5 D6 D7
SP CCR USP SR PC
All the other special Symbols, Mnemonics and Directive names may be defined
and used as Labels, or may be implemented as Macros, but be careful when doing
this to avoid circular references, which will not be detected until the Macro
nesting level is exceeded, or a write error results from the disk being full.
For example, if you redefine JSR as a Macro, and want to use it in the
Macro definition, don't call the assembler with the -CC switch, and be sure
to use a different case within the Macro text to get the assembler to recog-
nize the Mnemonic, which is case-insensitive, from the Macro name. This allows
the maximum flexibility for the assembler, with only a minimum of care from
the programmer.
==============================================================================
Error Messages:
The assembler uses as much logic as possible to generate a line of code
in spite of erroneous input. If a reliable evaluation can be made, a source
line will be interpreted regardless of errors, however some of these lines
may not be what you meant. Even the little bit of DWIM in this assembler
occupies a lot of code space. Because assembly of erroneous lines is attempted
where possible, you may find multiple error messages referring to the same
line. The listing file will only contain the first error detected, however the
screen list or error file will also list the errors in the order they were
detected. Some errors may generate errors later, especially if typing errors
cause the assembler to find an item it thinks is an undefined symbol in an
expression, and you later used this symbol for another purpose. The following
is a list of error messages, and explanations:
1: Error in Expression Value
The expression being evaluated contained some garbage.
2: Duplicate Line Label
An attempt at defining a Label twice was detected. This
error does not apply to ENTRY and EXTERN label types.
3: Undefined Label in Expression
The symbol or label used in the expression was not defined
anywhere in the source file.
4: Syntax Error
The assembler could make no sense of what you were trying to
tell it to do.
5: Operand Too Large
The operand was greater than the value allowed for the
operation being performed.
6: Invalid Register Specified
The register called for in the current operation and what
was found are not compatable.
7: Undefined Mnemonic or Command
An item in the Mnemonic field is not a defined Macro or
valid mnemonic or directive. May also be caused by using
a label outside of column one without a colon following it.
8: Improper use of Unary Operator
A Unary operator ('-' or '~') was found right after another
math operator. The expression evaluator cannot handle this,
so it is ignored and this message is output.
9: Division by Zero
A Division or Modulo operation was attempted where the right
hand value was zero or undefined. The result of this operation
is set to zero.
10: Too Many Right Parentheses
More right parentheses were found than left parentheses.
11: Missing Right Parenthesis
More left parentheses were used than right parentheses.
12: Too Many Parenthesis Levels
More than 16 levels of parentheses were attempted to
be opened.
13: Invalid Character in Expression
A character was found in the expression that is not
any of the defined mathops, numbers, symbol characters
or newline characters.
14: Closing Quote Absent
No closing quote on a character constant was found.
15: Operand Field Missing
An operand was needed, and was not there.
16: Bit Operand Required
The expression needs a bit operand, and what was found was
not of the required type.
17: Invalid Bit Specified
The data found cannot be used legally to specify a bit.
18: Immediate (#) Operand Needed
The data given was not preceded by the '#' (pound) sign,
and needed to be.
19: Branch or Jump Out-of-Range
The address evaluated is outside of the range allowable for
the branch of jump mnemonic specified.
** Command Line Required **
The message output when no arguments are present on the
command-line (you need at least the source filename.)
Also a Fatal error.
** Unrecognized Switch **
A switch or a character within a switch was not one of
the valid switches. Not a Fatal error.
** File Write Error **
An error occurred during a file write, as reported from
AmigaDOS. May be caused by a full disk.
** Source Filename Missing **
The source filename was not present, corrupt or was given
twice. A Fatal error.
** Parameter Too Long **
An Item on the command-line was too long to be evaluated.
Also Fatal.
** Insufficient Free Memory **
This error occurs when the memory pool does not contain
enough memory in a size large enough for the request
from the assembler to be filled. Execution stops
immediately.
** Too many Include Files **
This error occurs when you try to open the ninth Include
file before closing one.
** Couldn't open Source file **
AmigaDOS did not return information indicating that the source
file was ready to be read from (or it isn't there.) No
assembly will take place without a source file.
** Couldn't open Object file **
A Dos error occurred trying to open the object file.
** Couldn't open Listing file **
Same error from listing file open attempt.
** Couldn't open Error file **
Like above, but on error file attempt.
33: ENDMAC Command missing
The end of the source file was reached, and the assembler
was still saving a macro definition.
34: Too Many Parameters present
More parameters than the assembler has space to store
were found.
35: Parameter Too Long
An item in an expression or an operand was longer than the
defined limit.
36: Closing Quote Missing
A string definition should be bounded on both ends with
matching quotes.
37: No Label on Line
No label was present for the Directive to act upon.
38: Macro called using Symbol label
A symbol name found in the mnemonic field was attempted
to be used as a Macro, and was found to be a Label.
** Too many nested Macros **
This Fatal error occurs when the ninth Macro call is
issued before any of the previous Macro calls have ended.
40: Macro redefinition Error
The name used with the MACRO command is already the name
of a previously defined Macro.
41: ENDMAC command without MACRO definition
You didn't use the MACRO command to define your Macro, or
you issued the ENDMAC command twice. If you are attempting
to get two or more exit points from a macro, use the
MEXIT Directive.
** INCLUDE file unable to be opened **
This Error occurs when the filename associated with the
INCLUDE command was not found after the include directory
list was exhausted.
** Source or Include file line too long **
An input line read from disk contained more than 255
characters in a row without a carriage return or
linefeed.
44: Not enough Macro parameters supplied
An expansion was attempted and there were not enough
parameters on the Macro call line. This may be relaxed
with a command-line switch.
45: Label Value changed between passes
This unusual error occurs when the value of a Line Label
is different on the second pass than it was on the first
pass. The whole assembly file is probably corrupt, and
it is likely that the message will repeat with every
subsequent Line Label found. Forward references and
absolute references to SETVAL Labels, or conditional
compilation based on SETVAL Labels are the likely
culprits behind this error.
46: Invalid Label - Forward Referenced
A Label which was referenced before it was used was later
found in a context other than usage as a relative location.
47: Local Definition of External Symbol not allowed
If you declared a Symbol to be EXTERNal, you cannot define
it within the current assembly. Use the ENTRY Directive
instead if this is what you want.
48: Unavailable Addressing Mode Used
The addressing mode used for the Mnemonic on this
line is not one which is allowable for that
Mnemonic.
49: Invalid Item in External Reference Expression
An external reference included an item which did not
belong there. This also occurs on an attempt to
generate PC relative references to external addresses.
** Too Many Section Definitions (Limit = 255) **
The message is self-explanatory.
51: Invalid Section Type - Section CODE used
An item found after the section name was not one of the valid
section types - CODE, TEXT, DATA or BSS. The type is set to
CODE.
52: Alignment Error - Pad Byte Added
All the 68000 Mnemonics and WORD and LONG oriented Directives
need to be aligned on an even address. The Assembler attempts
to correct this by adding a null byte to the previous
instruction, and adjusts the Program Counter and Label values
accordingly.
** Too Many Conditional Levels Attempted
The seventeenth conditional Directive was found before an
ENDIF Directive was.
** Conditional End without Conditional Statement
There are more ENDIF commands than matching conditional
Directives.
55: Relative Reference Outside of Current Section
An attempt to use a PC relative mode to a Line Label that
was not declared as an ENTRY label was attempted. Also
occurs on Data references to other sections without
using the ENTRY type-definition. This message may be
suppressed with a command-line switch.
56: Code not allowed in Data & Bss Sections
DATA sections may contain only initialized and uninitialized
data locations, and BSS sections may contain only un-
initialized (RESERVE) data.
57: Redefinition of an Equate not Allowed
You cannot change the value of a Label that has been EQUATEd.
58: Equate to previously SET Label Disallowed
A Label that was set cannot later be upgraded to an equate
in the same assembly. The assembler handles decisions on
equated labels, whose value cannot change, differently
than set labels, whose value may be redefined. Since the
length of 68000 instructions vary with the address mode,
a set label is always treated as a LONG value (unless
otherwise specified) and an equated label is treated
for the value it contains. Since the assembler always
attempts to use the shortest instruction length possible,
a change in the type of a label can cause bad code to be
generated.
===============================================================================
Addressing Modes:
The following models show the valid address modes for the 68000 processor
as they are recognized by the assembler:
( 'n' represents a digit from 0 to 7, X represents either 'D' or 'A'
for an address mode 'ALabel' represents a symbol with an absolute
or an external value, 'RLabel' represents a Line Label or an
ENTRY typed label, 'number' refers to an actual numerical value, and
the other items are what they are. Case is not significant except on
Label and Symbol Names. Defined REG Labels of the proper type may be
used in place of the register names.)
IMMEDIATE: #number #ALabel
DATA REGISTER DIRECT: Dn
ADDRESS REGISTER DIRECT: An SP
ADDRESS REGISTER INDIRECT: (An) (SP)
ADDRESS REGISTER INDIRECT WITH POST INCREMENT: (An)+ (SP)+
ADDRESS REGISTER INDIRECT WITH PREDECREMENT: -(An) -(SP)
ADDRESS REGISTER INDIRECT WITH DISPLACEMENT: number(An)
number(SP)
ALabel(An)
ALabel(SP)
ADDRESS REGISTER INDIRECT WITH DISPLACEMENT AND INDEX: number(An,Xn)
Alabel(An, Xn)
number(SP, Xn)
ALabel(SP,Xn)
PROGRAM COUNTER RELATIVE WITH DISPLACEMENT: RLabel
RLabel(PC)
number(PC)
PROGRAM COUNTER RELATIVE WITH DISPLACEMENT AND INDEX: RLabel(Xn)
RLabel(PC, Xn)
number(PC, Xn)
SHORT ABSOLUTE: ALabel number
(where the value is less than $007FFF or greater than $FF8000)
LONG ABSOLUTE: RLabel (to another section)
ALabel number
(where the value doesn't qualify for short mode)
SPECIAL: USP CCR SR
===============================================================================
Release History:
Version 1.0.1 Alpha1.........released 02-Jan-87.
Version 1.0.1 Beta1..........released 11-Jan-87.
Version 1.0.1 Beta2..........released 20-Jan-87.
Version 1.0.1................released 28-Feb-87.
Version 1.0.2................released 14-Apr-87.
Changes: 1. Error messages now also contain the name of the
file containing the error.
2. DB (and DC.B) now correctly handle multiple operands
and character strings that contain spaces no longer
have the spaces removed.
3. The parameters on a macro call line are passed to
the macro quotes and all.
4. The expression evaluator will now accept multiple
character sequences, instead of just a single ascii
character. No specific limit is set on how many
characters can be included, but only the last four
will be retained.
5. The length specification on 68000 mnemonics using
one of the indexing modes is now passed to the
object code. (Only .L results in a different object
output. .W is assumed for all others.)
6. The REG command now works with single registers as
well as register lists.
7. Error 41 is now called as described.
8. Source lines containing only a label are now present
in the listing file.
9. References to #Label items which are not declared
as ENTRY (XDEF) will not stomp on low memory and
crash the system.
10. Program size has been reduced.
11. The assembler is now as much as 58% faster than
before. Benchmarks show it to be about 2 1/2 times
as fast as some other assemblers available.
12. The Heap space usable has been increased by a
factor of 4.
13. The \@ sequence is treated differently, with the
resultant 3-digit sequence remaining constant
for each macro level encountered, and being
incremented by each macro call, instead of the
strict pairing used in V.1.0.1.
Version 1.0.3................released 24-Apr-87.
Changes: 1. Error messages no longer are generated in the case
of EXTERN or ENTRY type multiple definitions.
More precisely, the second or subsequent usage is
ignored.
2. The counter for \@ has been changed so that it is
not incremented unless it is used by a macro. In
version 1.0.2, each macro call incremented the
counter, causing overflow in large source files
before 999 uses. This change should not cause the
need for source changes in files that assembled
correctly under the previous release, although a
reassembly will have different values used.
3. The expression evaluator has been changed slightly
on the rules regarding the use of the '*' op for
the PC location. This corrects prior problems in-
volving the assembler confusing the two uses that
made multiplication fail.
4. Labels and symbols that begin with a period will
now be recognized within expressions.
===============================================================================
A special note of gratitude to various members of ASDF (Amiga Software
Developers Forum), The Software Distillery (whose BLink reduced the many
hours spent relinking the source files during development), and especially
John Toebes, whose offhand remarks unknowingly provided much of the inspiration
to keep going. Also DJ JAMES and KEN S for their work in running down some
of the problems I missed.
===============================================================================
NOTE: Amiga and AmigaDOS are trademarks of Commodore Business Machines.
Intel is a trademark of the Intel Co.
MC68000 is a trademark of Motorola Co.
===============================================================================
<*|=|*> THE END <*|=|*>
==============================================================================
